Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| JavaTM 2 Platform Std. Ed. v1.4.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## java.awt
Interface Shape

All Known Implementing Classes:
  Area, CubicCurve2D, GeneralPath, Line2D, Polygon, QuadCurve2D, Rectangle, RectangularShape

public interface Shape

The `Shape` interface provides definitions for objects that represent some form of geometric shape. The `Shape` is described by a `PathIterator` object, which can express the outline of the `Shape` as well as a rule for determining how the outline divides the 2D plane into interior and exterior points. Each `Shape` object provides callbacks to get the bounding box of the geometry, determine whether points or rectangles lie partly or entirely within the interior of the `Shape`, and retrieve a `PathIterator` object that describes the trajectory path of the `Shape` outline.

Definition of insideness: A point is considered to lie inside a `Shape` if and only if:

- it lies completely inside the`Shape` boundary or
- it lies exactly on the `Shape` boundary and the space immediately adjacent to the point in the increasing `X` direction is entirely inside the boundary or
- it lies exactly on a horizontal boundary segment and the space immediately adjacent to the point in the increasing `Y` direction is inside the boundary.

The `contains` and `intersects` methods consider the interior of a `Shape` to be the area it encloses as if it were filled. This means that these methods consider unclosed shapes to be implicitly closed for the purpose of determining if a shape contains or intersects a rectangle or if a shape contains a point.

See Also:
  `PathIterator`, `AffineTransform`, `FlatteningPathIterator`, `GeneralPath`

Method Summary
`boolean` | `contains(double x, double y)` Tests if the specified coordinates are inside the boundary of the `Shape`.
`boolean` | `contains(double x, double y, double w, double h)` Tests if the interior of the `Shape` entirely contains the specified rectangular area.
`boolean` | `contains(Point2D p)` Tests if a specified `Point2D` is inside the boundary of the `Shape`.
`boolean` | `contains(Rectangle2D r)` Tests if the interior of the `Shape` entirely contains the specified `Rectangle2D`.
`Rectangle` | `getBounds()` Returns an integer `Rectangle` that completely encloses the `Shape`.
`Rectangle2D` | `getBounds2D()` Returns a high precision and more accurate bounding box of the `Shape` than the `getBounds` method.
`PathIterator` | `getPathIterator(AffineTransform at)` Returns an iterator object that iterates along the `Shape` boundary and provides access to the geometry of the `Shape` outline.
`PathIterator` | `getPathIterator(AffineTransform at, double flatness)` Returns an iterator object that iterates along the `Shape` boundary and provides access to a flattened view of the `Shape` outline geometry.
`boolean` | `intersects(double x, double y, double w, double h)` Tests if the interior of the `Shape` intersects the interior of a specified rectangular area.
`boolean` | `intersects(Rectangle2D r)` Tests if the interior of the `Shape` intersects the interior of a specified `Rectangle2D`.

Method Detail

### getBounds

    public Rectangle getBounds()

  Returns an integer `Rectangle` that completely encloses the `Shape`. Note that there is no guarantee that the returned `Rectangle` is the smallest bounding box that encloses the `Shape`, only that the `Shape` lies entirely within the indicated `Rectangle`. The returned `Rectangle` might also fail to completely enclose the `Shape` if the `Shape` overflows the limited range of the integer data type. The `getBounds2D` method generally returns a tighter bounding box due to its greater flexibility in representation.

  Returns:
    an integer `Rectangle` that completely encloses the `Shape`.
  See Also:
    `getBounds2D()`

### getBounds2D

    public Rectangle2D getBounds2D()

  Returns a high precision and more accurate bounding box of the `Shape` than the `getBounds` method. Note that there is no guarantee that the returned `Rectangle2D` is the smallest bounding box that encloses the `Shape`, only that the `Shape` lies entirely within the indicated `Rectangle2D`. The bounding box returned by this method is usually tighter than that returned by the `getBounds` method and never fails due to overflow problems since the return value can be an instance of the `Rectangle2D` that uses double precision values to store the dimensions.

  Returns:
    an instance of `Rectangle2D` that is a high-precision bounding box of the `Shape`.
  See Also:
    `getBounds()`

### contains

    public boolean contains(double x,
                            double y)

  Tests if the specified coordinates are inside the boundary of the `Shape`.

  Returns:
    `true` if the specified coordinates are inside the `Shape` boundary; `false` otherwise.

### contains

    public boolean contains(Point2D p)

  Tests if a specified `Point2D` is inside the boundary of the `Shape`.

  Parameters:
    `p` - a specified `Point2D`
  Returns:
    `true` if the specified `Point2D` is inside the boundary of the `Shape`; `false` otherwise.

### intersects

    public boolean intersects(double x,
                              double y,
                              double w,
                              double h)

  Tests if the interior of the `Shape` intersects the interior of a specified rectangular area. The rectangular area is considered to intersect the `Shape` if any point is contained in both the interior of the `Shape` and the specified rectangular area.

  This method might conservatively return `true` when:

  - there is a high probability that the rectangular area and the `Shape` intersect, but
  - the calculations to accurately determine this intersection are prohibitively expensive.
  This means that this method might return `true` even though the rectangular area does not intersect the `Shape`. The `Area` class can be used to perform more accurate computations of geometric intersection for any `Shape` object if a more precise answer is required.

  Parameters:
    `w` - the width of the specified rectangular area
    `h` - the height of the specified rectangular area
  Returns:
    `true` if the interior of the `Shape` and the interior of the rectangular area intersect, or are both highly likely to intersect and intersection calculations would be too expensive to perform; `false` otherwise.
  See Also:
    `Area`

### intersects

    public boolean intersects(Rectangle2D r)

  Tests if the interior of the `Shape` intersects the interior of a specified `Rectangle2D`. This method might conservatively return `true` when:
  - there is a high probability that the `Rectangle2D` and the `Shape` intersect, but
  - the calculations to accurately determine this intersection are prohibitively expensive.
  This means that this method might return `true` even though the `Rectangle2D` does not intersect the `Shape`.

  Parameters:
    `r` - the specified `Rectangle2D`
  Returns:
    `true` if the interior of the `Shape` and the interior of the specified `Rectangle2D` intersect, or are both highly likely to intersect and intersection calculations would be too expensive to perform; `false` otherwise.
  See Also:
    `intersects(double, double, double, double)`

### contains

    public boolean contains(double x,
                            double y,
                            double w,
                            double h)

  Tests if the interior of the `Shape` entirely contains the specified rectangular area. All coordinates that lie inside the rectangular area must lie within the `Shape` for the entire rectanglar area to be considered contained within the `Shape`.

  This method might conservatively return `false` when:

  - the `intersect` method returns `true` and
  - the calculations to determine whether or not the `Shape` entirely contains the rectangular area are prohibitively expensive.
  This means that this method might return `false` even though the `Shape` contains the rectangular area. The `Area` class can be used to perform more accurate computations of geometric intersection for any `Shape` object if a more precise answer is required.

  Parameters:
    `w` - the width of the specified rectangular area
    `h` - the height of the specified rectangular area
  Returns:
    `true` if the interior of the `Shape` entirely contains the specified rectangular area; `false` otherwise or, if the `Shape` contains the rectangular area and the `intersects` method returns `true` and the containment calculations would be too expensive to perform.
  See Also:
    `Area`, `intersects(double, double, double, double)`

### contains

    public boolean contains(Rectangle2D r)

  Tests if the interior of the `Shape` entirely contains the specified `Rectangle2D`. This method might conservatively return `false` when:
  - the `intersect` method returns `true` and
  - the calculations to determine whether or not the `Shape` entirely contains the `Rectangle2D` are prohibitively expensive.
  This means that this method might return `false` even though the `Shape` contains the `Rectangle2D`. The `Area` class can be used to perform more accurate computations of geometric intersection for any `Shape` object if a more precise answer is required.

  Parameters:
    `r` - The specified `Rectangle2D`
  Returns:
    `true` if the interior of the `Shape` entirely contains the `Rectangle2D`; `false` otherwise or, if the `Shape` contains the `Rectangle2D` and the `intersects` method returns `true` and the containment calculations would be too expensive to perform.
  See Also:
    `contains(double, double, double, double)`

### getPathIterator

    public PathIterator getPathIterator(AffineTransform at)

  Returns an iterator object that iterates along the `Shape` boundary and provides access to the geometry of the `Shape` outline. If an optional `AffineTransform` is specified, the coordinates returned in the iteration are transformed accordingly.

  Each call to this method returns a fresh `PathIterator` object that traverses the geometry of the `Shape` object independently from any other `PathIterator` objects in use at the same time.

  It is recommended, but not guaranteed, that objects implementing the `Shape` interface isolate iterations that are in process from any changes that might occur to the original object's geometry during such iterations.

  Before using a particular implementation of the `Shape` interface in more than one thread simultaneously, refer to its documentation to verify that it guarantees that iterations are isolated from modifications.

  Parameters:
    `at` - an optional `AffineTransform` to be applied to the coordinates as they are returned in the iteration, or `null` if untransformed coordinates are desired
  Returns:
    a new `PathIterator` object, which independently traverses the geometry of the `Shape`.

### getPathIterator

    public PathIterator getPathIterator(AffineTransform at,
                                        double flatness)

  Returns an iterator object that iterates along the `Shape` boundary and provides access to a flattened view of the `Shape` outline geometry.

  Only SEG_MOVETO, SEG_LINETO, and SEG_CLOSE point types are returned by the iterator.

  If an optional `AffineTransform` is specified, the coordinates returned in the iteration are transformed accordingly.

  The amount of subdivision of the curved segments is controlled by the `flatness` parameter, which specifies the maximum distance that any point on the unflattened transformed curve can deviate from the returned flattened path segments. Note that a limit on the accuracy of the flattened path might be silently imposed, causing very small flattening parameters to be treated as larger values. This limit, if there is one, is defined by the particular implementation that is used.

  Each call to this method returns a fresh `PathIterator` object that traverses the `Shape` object geometry independently from any other `PathIterator` objects in use at the same time.

  It is recommended, but not guaranteed, that objects implementing the `Shape` interface isolate iterations that are in process from any changes that might occur to the original object's geometry during such iterations.

  Before using a particular implementation of this interface in more than one thread simultaneously, refer to its documentation to verify that it guarantees that iterations are isolated from modifications.

  Parameters:
    `at` - an optional `AffineTransform` to be applied to the coordinates as they are returned in the iteration, or `null` if untransformed coordinates are desired
    `flatness` - the maximum distance that the line segments used to approximate the curved segments are allowed to deviate from any point on the original curve
  Returns:
    a new `PathIterator` that independently traverses the `Shape` geometry.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| JavaTM 2 Platform Std. Ed. v1.4.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Submit a bug or feature
For further API reference and developer documentation, see Java 2 SDK SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Java, Java 2D, and JDBC are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2002 Sun Microsystems, Inc. 901 San Antonio Road
Palo Alto, California, 94303, U.S.A. All Rights Reserved.